
             Help for SortTest v0.10 (11 Nov 2014)
             =====================================
             
Purpose
=======

To provide a test bed for integer sort routines, to help to make it easy to
create consistent, comparable results, with plug-in sort programs that just
do a sort. Test runs of the sorts are controlled by a simple script file.
This should enable effort to be concentrated on the sort programs themselves!

Installation
============

Simply copy !SortTest from the zip to any desired location.

Note: the following modules (or later) are required to run SortTest:

  TimerMod v4.17 for more accurate timing. 
    Written by Druck, and is available at http://www.armclub.org.uk/free/

  BASIC v1.33 for DIM LOCAL & assembler improvements.
    Pre-RISC OS v5 machines can softload a newer module available from ROOL.
    However, 26-bit machines are limited to 28MB WimpSlot maximum.

To Run SortTest
===============

Simply double-click on !SortTest, and it will run single-tasking, using the
Default file in the Tests directory.

SortTest can be run in a TaskWindow, but this will introduce some
variability in results.

SortTest uses parameters in the Tests file to create data (see below), then
it runs tests of sorts as specified, and displays the results, which are also
be saved with the same name as the Tests file used, with an 'O' appended.

If a Tests file has a filetype of SortTest &1EF then double-clicking it will
run that test, wherever the file is located.
*** Note: this filetype may change as it has not (yet) been allocated! ***

Fast assembler routines are used for copying and checking sorted data for
each sort, but the test data is only generated once per run.

After each sort all the sorted array is checked to ensure...
 	the integers are in non-decreasing sequence, else Error! 
 	the next word above the sorted array has not changed, else Overrun!
It does NOT check that all the original numbers still exist! 

The Sort Programs
=================

The plug-in Sort programs reside in the !SortTest.Sorts directory.

They consist of a Basic program, which must contain a sort function, and may
contain an initialisation function. It is recommended that the first line is
	REM > <programname> 
to aid any error messages.

The optional initialisation function must be named FN_<programname>_init. If
it exists, it will be called once before the sort routine is called, and can
perform any processing that is required once only. It can assemble a routine
if required. If Desc$ is assigned, it is displayed after the sort name.

The sort routine must be named FN_<programname>, must exist, and return 0.
It will have 3 parameters as follows (which can be called any name):
  array%()	Basic integer array for sorting, containing data.
  data%		Address of memory block containing integer data for sorting.
		Note these first 2 parameters refer to the same data!
  items%	Number of items to be sorted.
		The sort must start at item 0, up to item items%-1.

The Tests files
===============

The Tests files are simple text files, containing parameters for the test.
Null lines are ignored, as are comment lines (starting in #).
Parameters are all generally keyword:data which all are optional:

Title:	followed by a title for the display. Default blank.

Seed:	to set the seed for the RND function. Default 1234567
	TIME can be used for true randomness.
	
Data:	to set the type of data that is to be generated.
	Random		RND      from  -2147483648 to +2130706432 (Default)
	Positive	ABS(RND) from            0 to +2130706432
	Ascending	from 0 sequentially up to items.
	Descending	from items sequentially down to 0.
	Byte		RND(256)-1 from 0 to 255
	Others could be added.

Items: 	A comma-separated list of up to 50 numbers of items to sort.
	Default is 100,1000,5000
	
Stats:	To create a statistics file in CSV format of the results.
	0=no statistics (Default).   1=statistics file.
	Two sets of data are output: one with Items across and Sorts down,
	and another with Sorts across and Items down.
	They can be used to produce graphs of results!

Show:	Enables a display of sort data used, but only if Reporter running.
	0=no display (Default).  1=before.  2=after.  3=before & after.
	
Any other word at the start of a line is taken to be a sort program, but
anything after a blank is ignored. Programs must be in Sorts directory.
A maximum of 50 can be run in any one test.

Keywords may appear more than once ... but the last one is used!

Example Test files
==================

In the directory Tests there are some example SortTest files, which are
briefly described here:

All         runs a medium test of all the supplied Sorts.

Default     runs a quick test of all the supplied Sorts.
            This is used when !SortTest is run with no parameters.

JanDeBoer & Kuemmel
            run tests to simulate the sorts by Jan de Boer and Kuemmel
            that were posted in October 2014 on the ROOL Code Review 
            forum thread 'C to Basic struggle':
            https://www.riscosopen.org/forum/forums/3/topics/2886
            Note that some of these sorts only sort positive integers!

Sample      tests used to produce the Example output for the web site.

You are welcome to change these examples, but probably best to save with
another name to avoid a future release overwriting your changes.

Comments
========

*** If you find any improvements, add new sorts, or find any bugs,    ***
*** please send details to me at the address below.                   ***

History
=======

v0.10 11/11/2014 Initial beta version.


Martin Avison
armsort@avisoft.f9.co.uk
